import sumNthPowerDeviations from "./sum_nth_power_deviations.js";

/**
 * [样本方差](https://en.wikipedia.org/wiki/Variance#Sample_variance)
 * 是各数据点与均值偏离程度的平方和。样本方差通过[贝塞尔校正](https://en.wikipedia.org/wiki/Bessel's_correction)
 * 与普通方差区分：不使用输入数据长度直接除平方和，而是采用长度减一作为除数。
 * 该方法可修正从未知完整性的数据集中进行估计时产生的偏差。
 *
 * 参考文献:
 * * [Wolfram MathWorld 样本方差解释](http://mathworld.wolfram.com/SampleVariance.html)
 *
 * @param {Array<number>} x 包含两个及以上数据点的样本集
 * @throws {Error} 当输入数据长度小于2时抛出异常
 * @return {number} 样本方差值
 * @example
 * sampleVariance([1, 2, 3, 4, 5]); // => 2.5
 */
function sampleVariance(x) {
    if (x.length < 2) {
        throw new Error("sampleVariance函数需要至少两个数据点");
    }

    const sumSquaredDeviationsValue = sumNthPowerDeviations(x, 2);

    // 贝塞尔校正：对样本统计量的调整方法，用于补偿在样本计算中
    // 因自由度减少（相较于总体计算）带来的偏差
    const besselsCorrection = x.length - 1;

    // 计算校正后的均值作为方差估计
    return sumSquaredDeviationsValue / besselsCorrection;
}

export default sampleVariance;
